From 8ba996a6dbfb8a028b74ef43125c472ae6293c75 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 23 Jan 2016 01:51:48 -0500 Subject: [PATCH] container: Clarify the forall/foreach documentation Try to make the difference between these two functions clearer. --- gtk/gtkcontainer.c | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c index 2f4cf2a08a..69ffbd7df1 100644 --- a/gtk/gtkcontainer.c +++ b/gtk/gtkcontainer.c @@ -2387,12 +2387,14 @@ gtk_container_class_handle_border_width (GtkContainerClass *klass) * @callback: (scope call) (closure callback_data): a callback * @callback_data: callback user data * - * Invokes @callback on each child of @container, including children - * that are considered “internal” (implementation details of the - * container). “Internal” children generally weren’t added by the user - * of the container, but were added by the container implementation - * itself. Most applications should use gtk_container_foreach(), - * rather than gtk_container_forall(). + * Invokes @callback on each direct child of @container, including + * children that are considered “internal” (implementation details + * of the container). “Internal” children generally weren’t added + * by the user of the container, but were added by the container + * implementation itself. + * + * Most applications should use gtk_container_foreach(), rather + * than gtk_container_forall(). **/ void gtk_container_forall (GtkContainer *container, @@ -2416,10 +2418,15 @@ gtk_container_forall (GtkContainer *container, * @callback: (scope call): a callback * @callback_data: callback user data * - * Invokes @callback on each non-internal child of @container. See - * gtk_container_forall() for details on what constitutes an - * “internal” child. Most applications should use - * gtk_container_foreach(), rather than gtk_container_forall(). + * Invokes @callback on each non-internal child of @container. + * See gtk_container_forall() for details on what constitutes + * an “internal” child. For all practical purposes, this function + * should iterate over precisely those child widgets that were + * added to the container by the application with explicit add() + * calls. + * + * Most applications should use gtk_container_foreach(), + * rather than gtk_container_forall(). **/ void gtk_container_foreach (GtkContainer *container, -- 2.30.2